MacUser Mac Bin 40/MACUSER-MACBIN40A-1997-03.ISO.7z/MACUSER-MACBIN40A-1997-03.ISO/特集⁄オンラインソフト/ゲーム＆アミューズメント/アミューズメント/Citron 1.07J⁄E/収録XCMD説明＆サンプルスタック/XCMD⁄XFCN説明書/Plum説明書

Text File | 1996-12-18 | 21KB | 449 lines

　Plum XCMDは、HyperCard2.0より標準添付されているPicture XCMDの機能をほぼ網羅し、なおかつ表示時に様々な視覚効果をつける事のできるXCMDです。
　Plum XCMDは、落合　徹（ちゃい）が著作権を所有しています。自作のスタックなどに利用する場合は、当ドキュメントの「使用上の注意」の項を良く読んでからご使用ください。
　なお、自作のスタック等にインストールする場合は、CitronをHomeスタックへインストールするか、ResEdit等のリソース関連ツールでPlum XCMDその他の関連リソースをコピーしてください。

【Plum XCMD】（Version 1.28      CodeWarrior Gold10使用 1996/12）

　Plumは、HyperCardのPictureコマンドの上位互換を目指して作成されたPICT画像表示XCMDです。
　Plumの動作には32bit ColorQuickDrawが必要です。また、漢字Talk 7以降のシステムが必要です（JLKによる動作チェックはしていません）。動作チェックは漢字Talk 7.5.1で行いました。
　QuickTimeの圧縮機能を利用したPICTファイルの表示も可能ですが、その場合はQuickTimeが必要です。

０．更新履歴
（Version 1.28      CodeWarrior Gold10使用 1996/12）
  “newPictureFrom...”プロパティにおいて、newPictureFromResFileName◆◆等の形式で指定を行う場合に、容易にプロパティ名称の31バイト制限（HyperCardによる仕様）を越えてしまうので、省略形式を用意した。

（Version 1.27      CodeWarrior Gold10使用 1996/11）
  特製WDEF“FreeFrame”を簡単に使用できる様にするため、ウインドウスタイルにFreeFrame形式を追加

（Version 1.26      CodeWarrior Gold9使用 1996/9）
  タイプにResFineNameを指定した場合、リソース名称が正しく処理できないバグを修正

（Version 1.25      CodeWarrior Gold9使用 1996/6）
  Power Macintoshネイティブのバージョンも新たに作成
  Citron添付用に、名称を今までのPowerPictureからPlumに変更
  前のバージョンでは視覚効果にICONやPICTリソースを用いるものがあったが、これらHyperCardでも用いる標準リソースではIDのバッティング等が心配されるので、IObj、PObjという独自リソースを用いる様に変更
  視覚効果のリストを作成するためのコマンドを新設
  その他、マイナーバグフィックス

（Version 1.24      THINK C 6.0使用 1994/12）
  ResFile指定時にファイルをオープンできないバグを修正

（Version 1.22      THINK C 6.0使用 1994/8）
  マイナーバグフィックス
　公開バージョン

（Version 1.10      THINK C 6.0使用 1994/6）
  調整バージョン

（Version 1.00      THINK C 6.0使用 1993/12）
  初回完成バージョン

１．標準Pictureコマンドとの相違点

　Plumは標準Pictureコマンドの以下の仕様をサポートしていません。
・globalRectプロパティでの、マルチスクリーン対応
・windoid表示でのドラッグによるサイズ変更
・depthプロパティ（指定できますが、意味を持ちません）
・MacPaintのファイルの読み込み

　Plumは標準Pictureコマンドに対して、以下の拡張機能を有しています。
・描画時に視覚効果を施すことができる
・表示されているウインドウの絵を変更できる
・ウインドウの中でPICT画像の描画・消去を実行できる

２．Picture表示関係以外の機能

  PlumにはPICT表示機能とは別の機能があります。
  Previewつきのファイルダイアログを使用するコマンドと、カラー環境を調べるコマンドです。また、使用できる視覚効果を調べる機能も有しています。

  ファイルダイアログを使用するには以下の書式を使用します。

    Plum GetFile,PICT
  あるいは
    Plum GetFile,Picture
　です。

  ファイルダイアログが現われてフォルダーとPICTファイルだけがリストに表示されます。
　ファイルを選択すると、変数the resultにそのファイルのフルパスが返されます。
  キャンセルボタンを押した場合には、変数the resultがemptyになります。

　HyperTalkのAnswer fileコマンドと違うのは以下の点です。
・パスをthe resultに返すこと
・パスの長さに255バイトの制限がないこと
・Previewを表示可能なこと（QuickTimeがインストールされている必要があります。インストールされていない場合はPreview機能は使用できません）

　カラー環境を調べる時は以下の書式を使用します。

　　Plum SysEnvirons

　the resultに以下のフォーマットで情報が返されます。

　QuickTimeバージョン<return> ColorQuickDraw種類<return> Macintosh機種名

　・QuickTimeバージョン
　　QuickTimeがインストールされていない時は、no QuickTimeが返されます。
　　インストールされている時はQuickTime <バージョン番号>が返されます。

　・ColorQuickDraw種類
　　ColorQuickDrawがインストールされていない時はno QuickDrawが
　　8bit ColorQuickDrawがインストールされている時は8 bit ColorQuickDraw、
　　32bit ColorQuickDrawの場合は32 bit ColorQuickDrawと返されます。

　使用できる視覚効果を調べるときは以下の書式を使用します。

　　Plum EffectInfo,IncludeEffect
　　Plum EffectInfo,NameListWithIDList,"{PAT#/PPIL/PICL}"

　the resultに以下のフォーマットで情報が返されます。
　・IncludeEffectの場合
　　描画系（後述）の視覚効果リストを返します。 ※先頭に「stamp」が２つ返される事がありますが、バグではなく、内部的な仕様によるものです。気になる場合は結果の先頭１行を削除して利用してください。

　効果名<return>効果名<return>効果名<return>...


　・NameListWithIDListの場合
　　ディゾルブ系（後述）の視覚効果リストを返します。実際に使用する場合は、呼び出し名の方を用います。※ディゾルブ系の視覚効果は３種類あり、それを４バイトのリソース名で指定する必要があります（書式参照）。

　効果名,呼び出し名<return>効果名,呼び出し名<return>効果名,呼び出し名<return>...


３．Picture機能

　Plumは以下の形式でPicture機能を実行します。

　　Plum ﾌｧｲﾙ名,ﾀｲﾌﾟ,ｳｲﾝﾄﾞｳｽﾀｲﾙ,表示,ﾃﾞﾌﾟｽ,ﾚｲﾔｰ,位置

　・ﾌｧｲﾙ名
　表示するPICTのファイル名（フルパス表記）あるいはリソース名を与えます。
　クリップボードのデータを表示する場合も、ウインドウ名として使用されますので省略しないでください。
　省略すると（ﾀｲﾌﾟがresourceでもclipboardでも無い場合に限る）ファイルダイアログが表示されてPICTファイルを尋ねて来ます。

　・ﾀｲﾌﾟ
　　PICTデータをどこから読み込むかを指定します。以下の内から選びます。
　　　File/Resource/Clipboard/ResFileID◆◆/ResFileName◆◆
　　省略するとFileが選ばれます。

　　　Fileを指定した場合はPICTファイルから読み込みます
　　　Resourceの場合はスタックに格納されているPICTリソースから読み込みます
　　　Clipboardの場合は現在のクリップボードから読み込みます
　　　ResFileIDの場合は指定したファイルのPICTリソースを読み込みます
　　　　※ResFileIDに続けてID数値を指定する（◆◆の部分）
　　　ResFineNameの場合は指定したファイルのPICTリソースを読み込みます
　　　　※ResFileNameに続けてリソース名称を指定する（◆◆の部分）

　・ｳｲﾝﾄﾞｳｽﾀｲﾙ
　　表示するウインドウの形式を指定します。以下の内から選びます。
　　　plain/zoom/document/roundRect/dialog/rect/shadow/windoid
　　　　　/windoidZoom/freeFrame/wdef◆◆
　　省略するとzoomが選ばれます。
    　　wdefの場合は、続けてウインドウ定義ID数値を指定します（◆◆の部分）。
　　　　　　※WDEFリソースはあらかじめスタックにインストールしておくこと
　　　　　　※ウインドウ定義ID ＝ WDEFリソースID×16＋バリエーション番号
　　　freeFrameの場合、FreeFrame WDEFがインストールされている必要があります。

　・表示
　　PICTデータ読み込み時にウインドウを表示するかを指定します。
　　以下の内から選びます。
　　　true/false/視覚効果
　　省略時はtrueが選ばれます。
　　　trueの場合は表示します
　　　falseの場合は表示しません
　　　視覚効果を指定した場合、その視覚効果を用いて表示します（視覚効果の項目参照）

　・ﾃﾞﾌﾟｽ
　　当XCMDでは意味をもちません。純正Pictureコマンドとの互換性のために指定ができるだけです。

　・ﾚｲﾔｰ
　　ウインドウをパレットレイヤーにおくかどうかを指定します。
　　以下の内から選びます。
　　　true/false
　　　trueの場合にパレットレイヤーにウインドウがおかれます。
　　省略時はウインドウスタイルによって決定されます。

　・位置
　　ウインドウの位置をローカル座標で指定します。
　　　四隅（対角）座標を指定する方法と左上座標を指定する方法が選べます。
　　省略すると画面の中心に来るようにウインドウが配置されます。
　　※文字変数か、引用符(")で囲んだ文字列で指定してください。

  以上のパラメーターを与えることで、PICTファイルをオープンします。
  ここまでの使用でMoviePlay呼び出し時にthe resultに返される可能性のあるエラーメッセージは以下の通りです。

　Error:No such volume（存在しないボリュームを指定した）
　Error:Couldn't allocate storage for path strings（パス作成中にメモリーが足りなくなった）
　Error:Empty file name was given（ファイル名が指定されていない）
　Error:Window location parameter structure error（ウインドウの位置指定に誤りがある）
　Error:Couldn't open data file（ファイルがオープンできなかった）
　Error:Don't exist data fork（ファイルにデータフォークが存在しない）
　Error:PICT data storage memory wasn't allocated（PICTデータをストアしておくためのメモリーが確保できなかった）
　Error:PICT File read failed!（ファイル読み込み中に異常が発生した）
　Error:Can't find PICT Resource from current File（PICTリソースが発見できなかった）
　Error:Can't find PICT from clipboard（クリップボードのデータがPICTではない）
　Error:Couldn't open resource file（リソースがオープン出来なかった）
　Error:Couldn't allocate storage for window variables（外部ウインドウ情報をストアするメモリーが確保できなかった）
　Error:Couldn't create XWindow（外部ウインドウが作成できなかった）

４．ウインドウを操作する

 Plumで作成したウインドウには、様々な機能が付加されています。
 操作にはHyperTalkのsendコマンドを用います。

 send可能なメッセージは以下の通りです

    show     hide
    erase    draw    effectErase    effectDraw
    valid    front

　show/hideはウインドウの表示／非表示を切り替えます
　eraseそのウインドウの画像を消去します
　drawはそのウインドウに設定されているPICTを描画します
　effectEraseは視覚効果をもって、そのウインドウの画像を消去します
　effectDrawはそのウインドウに設定されているPICTを描画します
　validはウインドウの全画面領域をアップデートします
　frontはウインドウを最前面に持ってきます

５．プロパティ

  ウインドウには以下のプロパティがあります。

　読み出しのみ可能なプロパティ
   originalRect
   pictureWidth
   pictureHeight
   properties
   powerProperties

　書き込みのみ可能なプロパティ
   newPictureFrom...

　読み書き可能なプロパティ
   height
   width
   visible
   loc
   globalLoc
   rect
   globalRect
   dithering
   scroll
   zoom
   scale
   effect
   eraseColor
   name
   scaleMode
   scrollCenter
   backMode
   powerScale
   eraseSaving
   suspendHide
   picture

　originalRectはウインドウに設定されているPICT画像の縦横の矩形サイズを返します。ウインドウのサイズでは無いので注意してください（矩形）
　pictureWidthはウインドウに設定されているPICT画像の幅を返します。ウインドウの幅では無いので注意してください（整数）
　pictureHeightはウインドウに設定されているPICT画像の高さを返します。ウインドウの高さでは無いので注意してください（整数）
　propertiesはウインドウの持っているプロパティ名を返します（文字列）
　powerPropertiesはpropertiesで返されるプロパティ名以外に、Plumで使用可能なプロパティ名を返します（文字列）
　newPictureFrom...はウインドウに別のPICT画像を設定します
　...の部分はどこからPICT画像を読み込むかで変化します。つまり、プロパティ名そのものを変えます。以下のバラエティがあります。
　・newPictureFromFile
　　PICTファイルから読み込みます
　　ファイルパスをプロパティ値として設定してください
　・newPictureFromResource
　　PICTリソースを読み込みます
　　リソース名をプロパティ値として設定してください
　・newPictureFromClipboard
　　クリップボードから読み込みます
　　この場合、設定するプロパティ値に意味はありません。適当な文字列を与えてください。
　・newPictureFromResFileID◆◆
　　指定したファイルのid◆◆のPICTリソースを読み込みます
　　ファイルパスをプロパティ値として設定してください
　・newPictureFromResFileName◆◆
　　指定したファイルの名前が◆◆のPICTリソースを読み込みます
　　ファイルパスをプロパティ値として設定してください
  ※HyperCardは、プロパティ名称に31バイトという長さの制限があります。そのため、newPictureFromResFileName◆◆等の長いバラエティを使用すると、◆◆の部分に指定できる長さが非常に短いものになってしまいます。そのため、Version 1.28以降からは、“newPictureFrom”の部分を“nPF”の3バイトで代用できる様にしてあります。
 　height，width，visible，loc，rectはHyperTalkのウインドウプロパティに準じます
　globalLoc，globalRect，ditheringはHyperTalkのピクチャーウインドウプロパティに準じます。ただし、globalRectのマルチスクリーン機能には対応していません。また、ditheringは指定できるだけで動作しません
　scroll，zoom，scaleは基本的にHyperTalkのピクチャーウインドウプロパティに準じます。ただし、この後に説明するプロパティによるモード指定により、若干の仕様追加があります
　effectは視覚効果を示します。値の詳細は視覚効果の項目を参照してください
　eraseColorは画像を消去したときの画面の色を示します(R,G,Bの整数リスト文字列）
　nameはウインドウのタイトルを示します（文字列）
　scaleModeはスケールモードを示します。以下の値が使用できます。
　・ScaleMode（デフォルト）
　　Pictureと同等のスケールモードです
　　scaleプロパティに-5〜5までの整数が使用できます
　　　0が原寸で、1だと2倍，2だと4倍……，-1なら1/2倍，-2なら1/4倍……
　・PowerScaleMode
　　単純な倍化スケールモードです
　　powerScaleプロパティに任意の数値を縦,横の整数リスト文字列が使用できます
　　　1,1で原寸、2,2で縦横2倍，3,3だと縦横3倍……，-2,-2で縦横1/2，-3,-3なら縦横1/3……
　　powerScaleプロパティの値に0を指定しても、1に置き換えられます
　・WindowRectangle
　　ウインドウの縦横のサイズに合わせて、画像を拡大縮小して表示します
　・WindowFit
　　ウインドウにフィットする様に、縦横比を維持したまま画像を拡大縮小します
　・WindowFitNotExpand
　　画像がウインドウより大きい場合、ウインドウにフィットする様に、縦横比を維持したまま画像を縮小します
　scrollCenterは画像が常にウインドウに対して中央に来る様にする動作を示します。デフォルトはfalseです。このプロパティがtrueの時はscrollプロパティは無効になります（真偽値）
　backModeは表示する画像がウインドウより小さい場合、画像以外の領域をどう処理するかを示します。以下の値が使用できます。
　・PatternMode（デフォルト）
　　pictureコマンドの様に、グレイのモノクロパターンが使用されます
　・EraseMode
　　eraseColorで塗りつぶします
　powerScaleはscaleModeがpowerScaleModeの場合に使用されます。scaleModeを参照してください（縦,横の整数リスト文字列）
　eraseSavingは画像描画前にウインドウを消去するのを抑止する動作を示します。デフォルトはfalseです。スクロールなどをさせる場合、ちらつきを防止するのに役立ちます（真偽値）
　suspendHideは他のアプリケーションに切り替えたりしてHyperCardがバックグラウンドに移行した時にウインドウを一時的に隠す動作を示します。デフォルトはfalseです（真偽値）
　pictureはウインドウに設定されている画像のPicHandleを示します。取り出した値を他のXCMD等で利用できます。このプロパティを違う値にセットする場合は、もとのPicHandleを破棄する必要があります。Macintoshのプログラムに詳しい方以外が使用するのは危険です（整数）

６．メッセージコールバック

  Plumは以下の時に、カレントカードに向けてメッセージを送ります。

  ・ウインドウ作成時（visibleの状態に関係なく）

            openPicture ウインドウ名,ウインドウID

  ・ウインドウ破棄時

            closePicture ウインドウ名

 ・newPictureFrom...プロパティ設定によるPICT画像割り当て変更に成功した時

            changePicture ウインドウ名

　　※設定したPICT画像名では無く、ウインドウ名が渡されることに注意してください。
　　　newPictureFrom...プロパティ設定による変更ではウインドウ名は変化しません。

   ・ウインドウ内でマウスクリックした時
　　（mouseDown時）

            mouseDownInPicture "クリックした座標"

　　（mouseDownに続けてウインドウ内でmouseUpした時）

            mouseUpInPicture "クリックした座標"

  ※カードスクリプトにメッセージを受け取るハンドラーが無い場合は、HyperCardのメッセージ継承パスにそって、メッセージを継承して行きます。

７．視覚効果

　Plumでは、画像の描画／消去時に視覚効果を用いる事ができます
　効果のスピードを指定することはできません。
　現在用意されているのは、以下の通りです。
　文章による説明ではピンと来ないかも知れません。サンプルスタックの「効果テスト」で視覚効果を実際に試してみてください。
（描画系）
  Stamp
　　効果を用いずに描画します
  CWWipe
  CCWWipe
　　時計回り／反時計回りにワイプします
  RandomSlit
  RandomSlitV
　　位置が不規則な線で画像が描画されます。Vは垂直ライン版
  RandomLine
  RandomLineV
　　位置、長さが不規則な線で描画されます。Vは垂直ライン版
  RandomSquare
　　不規則な位置に現れる四角のマスで画像が描画されます
  ZoomIn
  ZoomOut
　　ズームイン／アウトして画像が現れます
  ScrambleSlit
  ScrambleSlitV
　　水平／垂直方向（V版）の両端から１ライン毎に画像が描画されていき、真ん中で交差します
  ScrollDown
  ScrollUp
  ScrollLeft
  ScrollRight
　　画像が描画範囲でスクロールして現れます
  FromTopRight
  FromBottomLeft
  FromTopLeft
  FromBottomRight
　　名前で示される位置から、対角上のコーナーに向かってワイプします
  WipeLeft
  WipeRight
  WipeUp
  WipeDown
　　名前の方向にワイプします
  BarnDoorOpen
  BarnGateOpen
　　中心から両端に向かってワイプします。Doorは垂直に、Gateは水平に画像が現れます
  BarnDoorClose
  BarnGateClose
　　両端から中心に向かってワイプします。Doorは垂直に、Gateは水平に画像が現れます
（ディゾルブ系）
　ディゾルブ系はXCMDインストールスタックのディゾルブ指定用リソースに従ってディゾルブを行います
　それぞれの視覚効果名の後ろに（空白を置かないで）リソース番号を指定します
　ディゾルブはXCMDにプログラムコードとして記述されている描画系の視覚効果と違い、リソースによって振る舞いを新たに追加することが可能です。このリソースについてのフォーマット情報は有料にて公開します（調べれば簡単にわかるとは思いますが……）

  DissolvePat
　　PAT#リソースに従ってディゾルブを行います
　　提供時は128〜136が使用できます
  DissolveIcon
　　PICL及びIObjリソースに従ってディゾルブを行います
　　提供時は128〜133が使用できます
  DissolvePict
　　PPIL及びPObjリソースに従ってディゾルブを行います
　　提供時は128〜129が使用できます

※同じ効果を指定した場合は、なるべく同じ時間で処理を終了する様にプログラムしてありますが、スピードが遅い機種や描画範囲が大きい場合は、描画完了までのスピードが遅くなることがあります。
　逆に、一定以上速くなることは無いはずです。

8．XCMDバージョン

  以下の方法で、Plumのバージョンを調べることができます。

    Plum XCMDVersion

  the resultによって以下の書式のメッセージが取り出せます。

    Plum XCMD Version *.** by -Chai-
    Plum XCMD PPCVersion *.** by -Chai-　　　（Power Macintoshバージョンの場合）

  ４ワード目(*.**と表わしたところ）に必ずバージョンナンバーが格納されているので、チェックする場合はそれを対象にしてください。

9．Plumの使用上の注意

 PowerPicture XCMD 1994 (C) Copyright ちゃい=Chai=
 Plum XCMD 1996 (C) Copyright 落合　徹（ちゃい）

  当パッケージを使用してトラブルが起こった際に、本項を読んでいないといった理由は一切受け付けることはできません。内容主旨を理解したうえでご使用ください。

  再配付を行なう様な場合は許可を取ってください（店頭での配付や、他ネットでの配付も含む。有料・無料どちらの場合もお願いします）。
  個人的使用、およびそれに準ずる範囲内を越えた利用の際は、次項の注意をよく理解した上で使用してください。

  当パッケージを使ったことによって生じた直接、間接の損害については、権利者および配付者は一切の責を負わないこととします。あくまで使用者の責任の範囲で運用を行なってください。

10．XCMD/XFCNの使用上の注意

　当XCMD/XFCNの著作権その他の権利は落合　徹（ちゃい）が所有しています。無断で外部使用することを禁じます。この項の説明はstart usingなどで間接的にXCMD/XFCNを使用する場合（Citronでの利用）も、同じ扱いとします。

　Citronの登録ユーザーの方は、個人的使用、およびそれに準ずる範囲内で、自由にご使用ください。
　PDSその他等で配付する場合は以下の通りとなります。いずれの場合も、配布者はCitronの登録ユーザーである必要があります。

  ･フリーウエアに収録して配付の場合は、XCMD使用料(配付ソフト一種につき￥１０００)をいただきます。
  ･シェアウエアもしくはそれに準ずる形式の配付の場合は（あるいはフリーウエアでも有償にて配付する場合）、XCMD使用料(配付ソフト一種につき￥５０００)をいただきます。
  ･業務目的で使用する場合、利益を生む配付（市販も含む）を行なう場合は別途ご相談ください。XCMD使用料およびライセンス料をいただきます。
 ・収録せずに利用する場合、すなわちstart using等でCitronに収録されたXCMD/XFCNを呼び出す場合は、上３項目に該当しません（つまり、無料ですし、連絡の必要もありません。Citronの登録ユーザーである必要はあります）。ただし、当然ながらXCMD/XFCNを使用するソフト（配布ソフト）のユーザーがCitronの登録ユーザーである必要があります。
 ・当XCMD/XFCNを収録したフリーウエア／シェアウエア（もしくはこれらに準ずる形式の配布形態）を雑誌等の媒体にて配布する場合、シェアウエアもしくはそれに準ずる形式の配付とみなして、配布ソフト作成者あるいは配布者（雑誌等の媒体）より、XCMD使用料(配付ソフト一種につき￥５０００)をいただきます。ただし、シェアウエアもしくはそれに準ずる形式の配付として既にXCMD使用料をいただいている場合は、二重に支払う必要はありません。

　連絡を取る場合は、２日〜１ヵ月の余裕をみておいてください。
　無断使用が発覚した場合、賠償請求させていただくことがあります。

　どの場合もドキュメント等に、以下の項目を記載してください。
　文章スタイル等は変更なさってもかまいません。

・Plum XCMDの著作権その他の権利は落合　徹（ちゃい）（Nifty:QGA01617）が所有しています。
・Plum XCMDを自作スタック等に使用なさりたい場合は、Nifty-Serve FMACHYPよりCitronスタックを入手し、登録した上でご利用ください。
・Plum XCMDを使ったことによって生じた直接、間接の損害については、XCMD作者および配付者は一切の責を負わないこととします。あくまで使用者の責任の範囲で運用を行なってください。
・無断使用が発覚した場合、賠償請求させていただくことがあります。

動作チェック環境
  漢字Talk 7.5.3
  HyperCard 2.3J
  QuickTime 2.5E
  Power Macintosh 8100/80AV,Macintosh LC630,Power Macintosh PowerBook 5300cs

　漢字Talk７以降なら、動作するものと思われます。